package com.puzzlebazar.client.util;


public interface Observable extends Releasable {

	/**
	 * Adds an observer to the set of observers for this object, provided 
	 * that it is not the same as some observer already in the set. The 
	 * order in which notifications will be delivered to multiple observers 
	 * is not specified. See the class comment. Observer is notified right after
	 * being added.
	 * 
	 * @param o an observer to be added
	 * @throws NullPointerException if the parameter o is null.
	 */
	public abstract void addObserver(Observer o) throws NullPointerException;

	/**
	 * Deletes an observer from the set of observers of this object. 
	 * 
	 * @param o the observer to be deleted.
	 */
	public abstract void deleteObserver(Observer o);

	/**
	 * Clears the observer list so that this object no longer has any observers. 
	 */
	public abstract void deleteObservers();

	/**
	 * Returns the number of observers of this Observable object. 
	 * 
	 * @return the number of observers of this object.
	 */
	public abstract int countObservers();

	/**
	 * If this object has changed, as indicated by the hasChanged method, 
	 * then notify all of its observers and then call the clearChanged 
	 * method to indicate that this object has no longer changed.
	 * 
	 * Each observer has its update method called with two arguments: 
	 * this observable object and null. 
	 * 
	 * Methods who plan on calling notifyObservers() should call 
	 * willNotifyObservers() at the beginning of the method. In situation 
	 * where multiple nested methods call notifyObservers, this mechanism 
	 * ensures that the observer will be notified only once by the outermost
	 * method.
	 */
	public void notifyObservers();
	
	/**
	 * If this object has changed, as indicated by the hasChanged method, 
	 * then notify all of its observers and then call the clearChanged 
	 * method to indicate that this object has no longer changed.
	 * 
	 * Each observer has its update method called with two arguments: 
	 * this observable object and the arg argument. 
	 * 
	 * Methods who plan on calling notifyObservers(arg) should NOT call 
	 * willNotifyObservers().
	 *
	 * @param arg any object.
	 */
	public void notifyObservers(Object arg);
		

	/**
	 * Marks this Observable object as having been changed; 
	 * the hasChanged method will now return true. 
	 */
	public void setChanged();

	
}